3.1.1 The WoMan Topic Cache

The amount of information that WoMan caches (in main memory and, optionally, saved to disc) is controlled by the user option woman-cache-level. There is a trade-off between the speed with which WoMan can find a file and the size of the cache, and the default setting gives a reasonable compromise.

The woman command always performs a certain amount of caching in main memory, but it can also write its cache to the filestore as a persistent cache under control of the user option woman-cache-filename. If persistent caching is turned on then WoMan re-loads its internal cache from the cache file almost instantaneously, so that there is never any perceptible start-up delay except when WoMan rebuilds its cache. Persistent caching is currently turned off by default. This is because users with persistent caching turned on may overlook the need to force WoMan to rebuild its cache the first time they run it after they have installed new man files; with persistent caching turned off, WoMan automatically rebuilds its cache every time it is run in a new Emacs session.

A prefix argument always causes the woman command (only) to rebuild its topic cache, and to re-save it to woman-cache-filename if this variable has a non-nil value. This is necessary if the names of any of the directories or files in the paths specified by woman-manpath or woman-path change. If WoMan user options that affect the cache are changed then WoMan will automatically update its cache file on disc (if one is in use) the next time it is run in a new Emacs session.